En la primera parte de esta serie de artículos sobre Fossil me concentré en las posibilidades que ofrece la inclusión de un wiki y un sistema de gestión de errores junto con el sistema de control de versiones (SCV) de forma general.
En esta segunda parte se describe el uso de Fossil como gestor de documentació a través de la funcionalidad que Fossil denomina documentación incrustada (embedded documentation).
Además de proporcionar un wiki para documentar el proyecto, existe la posibilidad de controlar las versiones de la documentación como un fichero más del repositorio. Esta posibilidad proporciona varias ventajas potenciales (según el propio autor de Fossil):
Aunque en la documentación no queda especialmente claro -al menos a mí-, parece que únicamente los ficheros con extensión wiki se consideran documentación y se interpretan siguiendo las reglas del wiki, mientras que el resto de tipos de ficheros (mimetypes) se muestran tal cual en el entorno web de Fossil.
En mi opinión el problema de esta documentación incrustada es que sólo se reconoce un pequeño subconjunto de etiquetas, tanto HTML como de markdown. Espero que a medida que Fossil madure se incremente el soporte para la sintaxis de markdown.
La posibilidad de incrustar documentación en el repositorio está presente en GitHub, por ejemplo, donde podemos utilizar diferentes lenguajes de marcas para la documentación del proyecto a través del fichero README: no sólo se soporta markdown, sino muchas otras opciones.
Si creamos la documentación de acuerdo con las reglas del wiki y la guardamos en Fossil, podemos acceder a ella a través de la URL virtual {IP_Servidor_FOSSIL}/doc/{version}/{nombre_fichero}.
{version} puede ser tanto el identificador de la versión del fichero, como el nombre de una rama; en este caso se muestra la última revisión de la documentación en esa rama... También puede ser tip, con lo que se muestra la última versión. También puede ser ckout, con lo que la documentación que se muestra es de nuestro repositorio local...
En fin, no será por opciones.
El adjetivo de incrustada cobra sentido cuando vemos que tanto los ficheros con extensión wiki como los txt se muestran en el wiki con el encabezado y el pie de página estandard, es decir, que parece como si estos documentos fueran parte del propio sistema de documentación del wiki y no un fichero más de nuestro repositorio.
El uso de la documentación incrustada y el wiki no es excluyente, aunque no tiene demasiado sentido utilizar ambos. De hecho, en la página de Fossil se ha optado por la documentación incrustada y en el wiki se indica claramente que la página es obsoleta, aunque el wiki sigue activo (pero se ha bloqueado la opción de crear nuevas páginas).
A la hora de crear la documentación los encabezados hay que ponerlos en HTML, pero las listas de elementos utilizan la sintaxis markdown... Los enlaces usan un formato particular, algo a medio camino entre enlaces markdown y enlaces al estilo Wikipedia... Es decir, para poder aprovechar las ventajas del wiki, primero hay que pasar por la inconveniencia de aprender un nuevo conjunto de reglas de marcado.
La cuestión entonces es, ¿la ventaja de ver la documentación incrustada en la web es suficiente frente a la posibilidad de de usar la sintaxis completa de markdown o HTML? Al fin y al cabo, podemos seguir usando el SCV para controlar las versiones de ficheros markdown/HTML, aunque no aparezcan incrustados en la web (pero sí mostrados, pues se reconoce el mimetype HTML).
La url virtual de acceso a la documentación es algo artificial y sería conveniente disponer de un link -como en la página de Fossil en la "barra de enlaces" del entorno web. Sin embargo, ese enlace a la documentación no aparece por defecto en la versión local.
Pese a las posibles ventajas de este forma de gestionar la documentación, el escaso soporte del lenguaje markdown y las restricciones aplicadas a las etiquetas HTML que se pueden usar en esta documentación incrustada limitan su potencial.
La url virtual de acceso a la documentación incrustada no es evidente ni accesible desde el entorno web (por defecto), lo que obliga a los usuarios del sistema a conocer cómo funciona esta documentación incrustada. Esto limita el uso de la documentación incrustada para usuarios ajenos al desarrollo del proyecto o sin un conocimiento específico del funcionamiento de Fossil.
En esta segunda parte se describe el uso de Fossil como gestor de documentació a través de la funcionalidad que Fossil denomina documentación incrustada (embedded documentation).
Documentación incrustada en Fossil
Una de las peculiaridades de Fossil es lo que he traducido como documentación incrustada (embedded documentation en la web de Fossil).Además de proporcionar un wiki para documentar el proyecto, existe la posibilidad de controlar las versiones de la documentación como un fichero más del repositorio. Esta posibilidad proporciona varias ventajas potenciales (según el propio autor de Fossil):
- La documentación se versiona junto al código que documenta, con lo que siempre queda claro qué versión del software documenta.
- Puedes editar los ficheros de la documentación utilizando tu editor favorito, en vez de estar limitado al entorno web del editor del wiki.
- Sólo la gente con permisos para realizar modificaciones en el repositorio (check-in) puede modificar la documentación. Esto puede ser una ventaja o una desventaja.
Aunque en la documentación no queda especialmente claro -al menos a mí-, parece que únicamente los ficheros con extensión wiki se consideran documentación y se interpretan siguiendo las reglas del wiki, mientras que el resto de tipos de ficheros (mimetypes) se muestran tal cual en el entorno web de Fossil.
En mi opinión el problema de esta documentación incrustada es que sólo se reconoce un pequeño subconjunto de etiquetas, tanto HTML como de markdown. Espero que a medida que Fossil madure se incremente el soporte para la sintaxis de markdown.
La posibilidad de incrustar documentación en el repositorio está presente en GitHub, por ejemplo, donde podemos utilizar diferentes lenguajes de marcas para la documentación del proyecto a través del fichero README: no sólo se soporta markdown, sino muchas otras opciones.
Si creamos la documentación de acuerdo con las reglas del wiki y la guardamos en Fossil, podemos acceder a ella a través de la URL virtual {IP_Servidor_FOSSIL}/doc/{version}/{nombre_fichero}.
{version} puede ser tanto el identificador de la versión del fichero, como el nombre de una rama; en este caso se muestra la última revisión de la documentación en esa rama... También puede ser tip, con lo que se muestra la última versión. También puede ser ckout, con lo que la documentación que se muestra es de nuestro repositorio local...
En fin, no será por opciones.
El adjetivo de incrustada cobra sentido cuando vemos que tanto los ficheros con extensión wiki como los txt se muestran en el wiki con el encabezado y el pie de página estandard, es decir, que parece como si estos documentos fueran parte del propio sistema de documentación del wiki y no un fichero más de nuestro repositorio.
El uso de la documentación incrustada y el wiki no es excluyente, aunque no tiene demasiado sentido utilizar ambos. De hecho, en la página de Fossil se ha optado por la documentación incrustada y en el wiki se indica claramente que la página es obsoleta, aunque el wiki sigue activo (pero se ha bloqueado la opción de crear nuevas páginas).
Puntos a favor y en contra de la documentación incrustada
Personalmente, la documentación incrustada me pareció una gran idea...al principio. Sin embargo, el hecho de no soportar markdown le hizo perder muchos puntos.A la hora de crear la documentación los encabezados hay que ponerlos en HTML, pero las listas de elementos utilizan la sintaxis markdown... Los enlaces usan un formato particular, algo a medio camino entre enlaces markdown y enlaces al estilo Wikipedia... Es decir, para poder aprovechar las ventajas del wiki, primero hay que pasar por la inconveniencia de aprender un nuevo conjunto de reglas de marcado.
La cuestión entonces es, ¿la ventaja de ver la documentación incrustada en la web es suficiente frente a la posibilidad de de usar la sintaxis completa de markdown o HTML? Al fin y al cabo, podemos seguir usando el SCV para controlar las versiones de ficheros markdown/HTML, aunque no aparezcan incrustados en la web (pero sí mostrados, pues se reconoce el mimetype HTML).
La url virtual de acceso a la documentación es algo artificial y sería conveniente disponer de un link -como en la página de Fossil en la "barra de enlaces" del entorno web. Sin embargo, ese enlace a la documentación no aparece por defecto en la versión local.
Resumen
En este artículo he comentado lo que Fossil denomina documentación incrustada: usar el sistema de control de versiones también para la documentación de nuestro proyecto.Pese a las posibles ventajas de este forma de gestionar la documentación, el escaso soporte del lenguaje markdown y las restricciones aplicadas a las etiquetas HTML que se pueden usar en esta documentación incrustada limitan su potencial.
La url virtual de acceso a la documentación incrustada no es evidente ni accesible desde el entorno web (por defecto), lo que obliga a los usuarios del sistema a conocer cómo funciona esta documentación incrustada. Esto limita el uso de la documentación incrustada para usuarios ajenos al desarrollo del proyecto o sin un conocimiento específico del funcionamiento de Fossil.
Comentarios